home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 426-450 / disk_436 / input / readme < prev    next >
Text File  |  1992-05-06  |  7KB  |  189 lines
  1. KEYBOARD INPUT MADE EASY
  2. © Copyright 1990 Timm Martin
  3.  
  4.  
  5. INTRODUCTION
  6.  
  7. This archive contains a few functions which should make reading input from
  8. the keyboard a snap.  Included are 6 files:
  9.  
  10.    README ...... what you are reading now
  11.    console.c ... functions to open and close the console device
  12.    input.c ..... a function to read keyboard input
  13.    input.h ..... header file for programs using these functions
  14.    test.c ...... test program showing you how to use these functions
  15.    test ........ executable form of the test program
  16.  
  17. At the heart of this keyboard processor is an input function which "cooks"
  18. Intuition RAWKEY messages, returning a 16-bit number packed with all necessary
  19. key information.  This number contains not only the value of the key pressed,
  20. but also any qualifiers (such as the SHIFT key, ALT key, Amiga key, or CONTROL
  21. key).  The function will return all key presses including command keys
  22. (function keys, arrow keys, HELP, DELETE, BACKSPACE, RETURN, ESCAPE, and
  23. RETURN) and international dead keys (such as e-accent-grave received when you
  24. press ALT-g then e).
  25.  
  26.  
  27. LEGAL JUNK
  28.  
  29. Some of the source is copyrighted, but all of it may be used freely as long
  30. as the copyright notice remains intact.  You may use any of this source
  31. inside executable programs without acknowledgement of or compensation to the
  32. author (me!).
  33.  
  34. All of the source was written to conform to ANSI C standards and compiles
  35. cleanly using Manx C v5.0b (and compiler options -pas -wadpru).
  36.  
  37.  
  38. GETTING STARTED...QUICKLY!
  39.  
  40. --  Place the input.h header file in the current directory and add the
  41.     following line to the beginning of your source file:
  42.  
  43.         #include "input.h"
  44.  
  45. --  In your program startup function, call the console_open() function,
  46.     checking its return value.  If FALSE, you should end the program.
  47.  
  48. --  In your program cleanup function, call the console_close() function.
  49.  
  50. --  Be sure to set the RAWKEY flag in the IDCMPFlags member of your NewWindow
  51.     structure.
  52.  
  53. --  Inside your window input loop, check for a RAWKEY message class.  If
  54.     received, call the input_key() function, passing it a pointer to the
  55.     IntuiMessage.  If this function returns a non-zero value, then a key
  56.     has been pressed and you can process it.  For example:
  57.  
  58.         struct Window *window;
  59.         struct IntuiMessage *imessage;
  60.         USHORT key;
  61.  
  62.         while (imessage = (struct IntuiMessage *)GetMsg( window->UserPort ))
  63.         {
  64.           switch (imessage->Class == RAWKEY)
  65.           {
  66.             case RAWKEY:
  67.               if (key = input_key( imessage ))
  68.                 /* key was pressed -- do something with it */
  69.             case CLOSEWINDOW:
  70.               etc...
  71.           }
  72.         }
  73.  
  74. --  When processing a key, you first need find out whether the key was a
  75.     command key (such as F1, HELP, RETURN, UP-ARROW, etc.) or an ASCII
  76.     character (such as 'A', '3', 'k', etc.).  You can do this with the
  77.     KEY_COMMAND() macro (defined in input.h).  For example:
  78.  
  79.         if (KEY_COMMAND( key ))
  80.           /* is a command key */
  81.         else
  82.           /* is an ASCII character */
  83.  
  84.     Then you need to find out which key was pressed.  You can do this with
  85.     the KEY_VALUE() macro:
  86.  
  87.         char c;
  88.         c = KEY_VALUE( key );
  89.  
  90.     If this is a command key, then the key value will be a number between 1
  91.     and 20 as defined in input.h, such as COMMAND_F1, COMMAND_HELP,
  92.     COMMAND_UP_ARROW, etc.
  93.  
  94.     If this is an ASCII character, however, then the key value will just be
  95.     the value of the character itself, such as decimal 65 if the 'A' key was
  96.     pressed.
  97.  
  98. --  If you need to know if a qualifier was pressed with the key, you can use
  99.     the qualifier definitions in input.h.  For example:
  100.  
  101.         if (key & QUAL_CONTROL)  /* was the control key pressed? */
  102.         if (key & QUAL_LSHIFT)   /* was the left shift key pressed? */
  103.         if (key & QUAL_SHIFT)    /* was either shift key pressed? */
  104.         etc...
  105.  
  106. --  Compile the console.c and input.c source files.  Be sure to link these
  107.     files with your main program, for example (with the test.c program and
  108.     Manx C):
  109.  
  110.         ln test console input -lc
  111.  
  112.  
  113. TECHNICAL DETAILS
  114.  
  115. To convert Intuition RAWKEY messages into ASCII characters, the input_key()
  116. function uses the Amiga RawKeyConvert() function.  This function is not
  117. located in any ROM library, but rather, is a vector attached to the console
  118. device.  This means that you need to open console.device to use it.
  119.  
  120. The source file console.c was provided for your convenience.  It includes the
  121. console_open() function (which opens the console device, returning TRUE or
  122. FALSE whether successful) and the console_close() function (which closes the
  123. console device).
  124.  
  125. Each time you receive an Intuition RAWKEY message, you should call the
  126. input_key() function, sending it a pointer to the IntuiMessage.  Note that
  127. you may receive more than one RAWKEY message per key returned by input_key().
  128. Intuition sends a RAWKEY message each time a key is pressed OR released, and
  129. whenever a qualifier key is pressed or released.  The input_key() function
  130. filters out all extraneous messages and returns a non-zero value only when
  131. there's a key to be dealt with.
  132.  
  133. The input_key() function returns a unsigned short (16-bit) integer.  The
  134. information is laid out as follows:
  135.  
  136.     <-- MOST SIGNIFICANT BYTE --->  <-- LEAST SIGNIFICANT BYTE -->
  137.     15  14  13  12  11  10  09  08  07  06  05  04  03  02  01  00  <--BITS
  138.     RG  LG  RA  LA  CT  RS  LS  CO  <-------- key value --------->
  139.  
  140. where if the bits are set (==1) indicate:
  141.  
  142.     BIT  MEANING
  143.     ---  -----------------------------------
  144.     15   right AMIGA key was pressed
  145.     14   left AMIGA key was pressed
  146.     13   right ALT key was pressed
  147.     12   left ALT key was pressed
  148.     11   CONTROL key was pressed
  149.     10   right SHIFT key was pressed
  150.     09   left SHIFT key was pressed
  151.     08   one of the command keys was pressed
  152.  
  153. The least significant byte (represented by bits 0 through 7) holds the value
  154. of the key pressed.  If a command key was pressed, bit 08 will be set and the
  155. key value in bits 0 through 7 will contain a number between 1 and 20 as
  156. defined in input.h:
  157.  
  158.     VALUE  #define              CORRESPONDING COMMAND KEY
  159.     -----  -------------------  -------------------------
  160.      1     COMMAND_F1           F1 key
  161.      2     COMMAND_F2           F2 key
  162.      3     COMMAND_F3           F3 key
  163.      4     COMMAND_F4           F4 key
  164.      5     COMMAND_F5           F5 key
  165.      6     COMMAND_F6           F6 key
  166.      7     COMMAND_F7           F7 key
  167.      8     COMMAND_F8           F8 key
  168.      9     COMMAND_F9           F9 key
  169.     10     COMMAND_F10          F10 key
  170.     11     COMMAND_TAB          TAB key
  171.     12     COMMAND_DELETE       DELETE key
  172.     13     COMMAND_ESCAPE       ESCAPE key
  173.     14     COMMAND_BACKSPACE    BACKSPACE key
  174.     15     COMMAND_HELP         HELP key
  175.     16     COMMAND_RETURN       RETURN key
  176.     17     COMMAND_UP_ARROW     UP_ARROW key
  177.     18     COMMAND_DOWN_ARROW   DOWN_ARROW key
  178.     19     COMMAND_LEFT_ARROW   LEFT_ARROW key
  179.     20     COMMAND_RIGHT_ARROW  RIGHT_ARROW key
  180.  
  181. If a character key was pressed, then bit 08 will be cleared and bits 0
  182. through 7 will represent the ASCII value of the character.
  183.  
  184. For more information on how this 16-bit integer is created, see the input.c
  185. source file.
  186.  
  187.  
  188. /*--- END OF TEXT ---*/
  189.